.\" t
.TH "lemsctl" "1M" "Jun 28, 2006" "1\&.2\&.0"
.SH NAME
lemsctl \- Pass messages to a Linuxha.net Lems Daemon

.SH SYNOPSIS
.TS
l.
lemsctl \fB-A|--application\fP \fIapp\fP \fB-M|--msg\fP \fImsg\fP [\fB--verbose\fP]
        [\fB--nochecksums\fP]
       Pass message to Lems Daemon

lemsctl \fB-?\fP
       Show brief usage information
.TE

.SH DESCRIPTION
This utility allows the administrator to send a message to a particular
Lems daemon running for an application. Of course if the application is
not currently running an error will be returned.

This routine does not need to be run on the node where the application is
running, since it will ensure communication to the correct node is made.

Once the message has been dealt with the output will be sent to the 
standard output. The message may consist one or more lines of output, 
depending on the request.

.SH COMMON MESSAGES
This list of supported messages that can be sent to the daemon varies
depending on the software release. However the list below is supported for
all recent releases (from 1.0.0 onwards).

.TP 4
.B GET_STAT
This will return summary status information for all monitors that are 
currently registers with the daemon for the particular application. 
Each registered monitor will be shown on a new line of output, and the 
information will appear in the following format:

.TS
l.
name,runtime,interval,type
.TE

The fields on this line are:

.RS 4
.TP 6
.B name
The label or name that has been given to this monitor, (this is needed 
because the same type of monitor can be run more than once).
.TP
.B runtime
The next step after which the check is scheduled to be run. This is the
UNIX time, (time in seconds since 01/01/1970), and may include a decimal
point.

If this is 0 it indicates that the specified monitor is not currently
scheduled to run.
.TP
.B interval
The interval in seconds between which the specified check is run. This
can contain a fraction component.
.TP
.B type
The monitor type - this indicates the Perl module that defines the functionality
for this monitor.

.RE

.TP 4
.B GET_VSTAT
This request will returned verbose statistics information about each
of the currently registered monitors for the Lems daemon.

This call will request information from each monitor registered and hence
the amount of output generated depends on whether the monitors support this
request and the type of monitor.

The format of the output generated will be as follows:

.TS
l.
<name-detail-start>
monitor text
<name-detail-end>
.TE

In the above text "name" is the name of the monitor, not the type of
the monitor. The "monitor text" is 0 or more lines depending on whether the
monitor supports the \fBVSTAT\fP request and how much output this type of 
monitor generates.

For information on the format of the data for each monitor please view the
Administrators Guide.

.TP
.B GET_MSTAT
This detail is particularly useful when debugging problems since it 
captures details about internal module failures within the Lems daemon for
the specified application. The format will be as follows - one line for
each monitor configured.

.TS
l.
name module status:N reason
.TE

.RS 4
.TP 6
.B name
The label or name that has been given to this monitor, (this is needed 
because the same type of monitor can be run more than once).
.TP
.B module
The name of the Perl source module that contains the running code for
the module in question.
.TP
.B status:N
The status can be either 'loaded' - if it was successfully loaded when
the Lems daemon was started or last reconfigured. If it did not load the
status will be 'failed'.

The 'N' refers to the number of failures in the Perl module that have
occurred since that point - anything other than 0 should be investigated
by the developers.
.TP
.B reason
When the status is 'failed' this will contain text describing what failed, 
otherwise the field will be empty.
.RE

.TP 4
.B ABORT
Indicates that the Lems monitor should be aborted.
.TP
\fBPAUSE\fP [monitor_name]
If a monitor name is specified that particular monitor stops running. If no
arguments are specified all configured monitors are paused.
.TP
\fBRESUME\fP [monitor_name]
This will resume a previously paused monitor. If no monitor name is
specified all currently paused monitors will be resumed.
.TP
\fBRECONFIGURE\fP
Trigger a complete daemon reconfiguration. This is used by the
\fIclbuildapp(1M)\fP if the application is currently running. However if the 
Lems configuration is altered then it is sometimes more straightforward
simply to pass this message to the daemon directly.

When the daemon handles a reconfiguration event all entries in the configuration
file are re-checked. Only new modules are loaded - existing modules are kept.
.TP
\fBREMOVE\fP monitor_name
When running this command it will unload the specified monitor and hence it 
will no longer be run or show in the output of the \fIclstat(1M)\fP command.

It is not recommended that this feature be used unless advised since it
may impact the functionality of the \fIclstat(1M)\fP command and
any utility that makes use of the output it generates.

.TP
\fBINSTALL\fP monitor_name
Installs a new monitor (hence the specified monitor must not currently be
loaded). During this process all monitor scripts are paused since the
Lems configuration file is re-scanned to ensure it is valid, and all 
information about the specified module can be found and is valid.

Once the installation is complete the scheduled tasks are resumed, including
the new monitor just loaded.

.TP
\fBLOGCYCLE\fP count
When running in verbose mode, (which is recommended and typically happens when
started via \fIclrunapp(1M)\fP or \fBclstartapp(1M)\fP), the Lems daemon is
likely to generate a significant amount of output over time. Since it
keeps the log file open for writing at all times, management of such files
is not straightforward.

Fortunately this command is available and it will stop writing to the
current log file, cycle it, (i.e. add a ".1" extension), and then
resume writing to a new file. Existing cycled log files are kept up to a
maximum number of iterations specified on the command line, (which can be
up to 99).

.SH ARGUMENTS
Only a small number of options are currently avaiable currently.

.TP 8
.B --verbose
Gives some output to the standard output regarding the operation of the
command - nothing of any real detail is currently produced, however.
.TP
.B --application
Connect to the Lems daemon for the specified application. This flag is 
mandatory. If the specified appliation is not currently running then an
error will be produced.
.TP
.B --msg
The message to send to the Lems daemon for this application.
.TP
.B --nochecksums
Normally if the cluster or application configuration file 
have been modified whilst the cluster is running the
checksums which are used to indicate the last sane and checked configuration 
will not be valid. In such instances many of the Linuxha.net commands, including
this will not will not function. If necessary the \fB--nochecksums\fP can be
used to overcome this until the cluster or application configuration are
next rebuilt.

.SH EXIT STATUS
The \fIlemsctl(1M)\fP utility makes use of many error codes, but in summary
it will return a non-zero number for an error or zero if the message was
past to the Lems daemon and the response was returned.

Please note that if the command "failed" on the Lems daemon but it managed
to send a response then the \fIlemsctl(1M)\fP will return a successful
exit code.

.SH SEE ALSO
.TS
l l.
cldeamonctl(1M)	- Cluster status Daemon Communication Tool
clnetctl(1M)	- Network status Daemon Communication Tool
clhbdctl(1M)	- Heartbeat Daemon Communication Tool
clstat(1M)	- Show cluster status information
appconf.xml(5)	- Configuration of an application used by the cluster
clconf.xml(5)	- Overall cluster topology configuration file
lems.xml(5)	- Lems Daemon configuration file
.TE

.SH AUTHOR
The \fIlemsctl(1M)\fP utility was written by Simon Edwards, 2004-2006. The
author can be contacted via the website mentioned below.

.SH AVAILABILITY
This software is freely available from the Linuxha.net website - please see
\fBhttp://www.linuxha.net\fP for more details.

.SH WARRANTY
This is Open Source Software is per the GNU GPL. It is free to use and
distribute but \fIcomes with no warranty whatsoever\fP. For more information
on the license please see \fBwww.gnu.org/copyleft/gpl.html\fP.

